home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kopete / kopeteprotocol.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  8.4 KB  |  270 lines
  1. /*
  2.     kopeteprotocol.h - Kopete Protocol
  3.  
  4.     Copyright (c) 2002      by Duncan Mac-Vicar Prett <duncan@kde.org>
  5.     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
  6.     Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart@ tiscalinet.be>
  7.  
  8.     Kopete    (c) 2002-2004 by the Kopete developers  <kopete-devel@kde.org>
  9.  
  10.     *************************************************************************
  11.     *                                                                       *
  12.     * This library is free software; you can redistribute it and/or         *
  13.     * modify it under the terms of the GNU Lesser General Public            *
  14.     * License as published by the Free Software Foundation; either          *
  15.     * version 2 of the License, or (at your option) any later version.      *
  16.     *                                                                       *
  17.     *************************************************************************
  18. */
  19.  
  20. #ifndef KOPETEPROTOCOL_H
  21. #define KOPETEPROTOCOL_H
  22.  
  23. #include "kopeteplugin.h"
  24. #include "kopeteonlinestatus.h"
  25.  
  26. class KopeteEditAccountWidget;
  27. class AddContactPage;
  28.  
  29. #include "kopete_export.h"
  30.  
  31. namespace Kopete
  32. {
  33.  
  34. class Contact;
  35. class MetaContact;
  36. class Account;
  37.  
  38. /*namespace UI
  39. {
  40.     class EditAccountWidget;
  41.     class AddContactPage;
  42. }*/
  43.  
  44.  
  45. /**
  46.  * @brief base class of every protocols.
  47.  *
  48.  * A protocol is just a particular case of Plugin
  49.  *
  50.  * Protocol is an abstract class, you need to reimplement createNewAccount,
  51.  * createAddContactPage, createEditAccountWidget
  52.  *
  53.  *
  54.  * @author Duncan Mac-Vicar Prett <duncan@kde.org>
  55.  * @author Martijn Klingens       <klingens@kde.org>
  56.  * @author Olivier Goffart        <ogoffart @ tiscalinet.be>
  57.  */
  58. class KOPETE_EXPORT Protocol : public Plugin
  59. {
  60.     Q_OBJECT
  61.  
  62. public:
  63.  
  64.     /**
  65.      * @todo  Ideally, the destructor should be protected. but we need it public to allow QPtrList<Protocol>
  66.      */
  67.     virtual ~Protocol();
  68.  
  69.     /**
  70.      * @brief Create an empty Account
  71.      *
  72.      * This method is called during the loading of the config file.
  73.      * @param accountId - the account ID to create the account with. This is usually
  74.      * the login name of the account
  75.      *
  76.      * you don't need to register the account to the AccountManager in this function.
  77.      * But if you want to use this function don't forget to call  @ref AccountManager::registerAccount
  78.      *
  79.      * @return The new @ref Account object created by this function
  80.      */
  81.     virtual Account *createNewAccount( const QString &accountId ) = 0;
  82.  
  83.     /**
  84.      * @brief Create a new AddContactPage widget to be shown in the Add Contact Wizard.
  85.      *
  86.      * @return A new AddContactPage to be shown in the Add Contact Wizard
  87.      */
  88.     virtual AddContactPage *createAddContactWidget( QWidget *parent, Account *account ) = 0;
  89.  
  90.     /**
  91.      * @brief Create a new KopeteEditAccountWidget
  92.      *
  93.      * @return A new KopeteEditAccountWidget to be shown in the account part of the configurations.
  94.      *
  95.      * @param account is the KopeteAccount to edit. If it's 0L, then we create a new account
  96.      * @param parent The parent of the 'to be returned' widget
  97.      */
  98.     virtual KopeteEditAccountWidget * createEditAccountWidget( Account *account, QWidget *parent ) = 0;
  99.  
  100.  
  101.     /**
  102.      * @brief a bitmask of the capabilities of this protocol
  103.      * @sa @ref setCapabilities
  104.      */
  105.     unsigned int capabilities() const ;
  106.  
  107.  
  108.     /**
  109.      * @brief Available capabilities
  110.      *
  111.      * @ref capabilities() returns an ORed list of these, which
  112.      * the edit widget interperts to determine what buttons to show
  113.      */
  114.     enum Capabilities
  115.     {
  116.         BaseFgColor = 0x1,     ///< Setting the bg color of the whole edit widget / message
  117.         BaseBgColor = 0x2,     ///< Setting the fg color of the whole edit widget / message
  118.         RichFgColor = 0x4,       ///< Setting the fg/bg color of text portions individually
  119.         RichBgColor = 0x8,       ///< Setting the fg/bg color of text portions individually
  120.  
  121.         BaseFont = 0x10,        ///< Setting the font of the whole edit widget / message
  122.         RichFont = 0x20,       ///< Setting the font of text portions individually
  123.  
  124.         /// Setting the formatting of the whole edit widget / message
  125.         BaseUFormatting = 0x40,
  126.         BaseIFormatting = 0x80,
  127.         BaseBFormatting = 0x100,
  128.  
  129.         /// Setting the formatting of text portions individually
  130.         RichUFormatting = 0x200,
  131.         RichIFormatting = 0x400,
  132.         RichBFormatting = 0x800,
  133.  
  134.         Alignment = 0x1000,     ///< Setting the alignment of text portions
  135.  
  136.         /// Setting the formatting of the whole edit widget / message
  137.         BaseFormatting = BaseIFormatting | BaseUFormatting | BaseBFormatting,
  138.  
  139.         /// Setting the formatting of text portions individually
  140.         RichFormatting = RichIFormatting | RichUFormatting | RichBFormatting,
  141.  
  142.         RichColor = RichBgColor | RichFgColor,
  143.         BaseColor = BaseBgColor | BaseFgColor,
  144.  
  145.         //Shortcut for All of the above - full HTML
  146.         FullRTF =  RichFormatting | Alignment | RichFont | RichFgColor | RichBgColor ,
  147.  
  148.  
  149.         CanSendOffline = 0x10000 ///< If it's possible to send  offline messages
  150.     };
  151.  
  152.     /**
  153.      * @brief Returns the status used for contacts when accounts of this protocol are offline
  154.      */
  155.     Kopete::OnlineStatus accountOfflineStatus() const;
  156.  
  157.  
  158. protected:
  159.     /**
  160.      * @brief Constructor for Protocol
  161.      *
  162.      * @param instance The protocol's instance, every plugin needs to have a KInstance of its own
  163.      * @param parent The protocol's parent object
  164.      * @param name The protocol's name
  165.      */
  166.     Protocol( KInstance *instance, QObject *parent, const char *name );
  167.  
  168.     /**
  169.      * @brief Sets the capabilities of this protcol.
  170.      *
  171.      * The subclass contructor is a good place for calling it.
  172.      * @sa @ref capabilities()
  173.      */
  174.     void setCapabilities( unsigned int );
  175.  
  176. public:
  177.  
  178.     /**
  179.      * Reimplemented from Kopete::Plugin.
  180.      *
  181.      * This method disconnects all accounts and deletes them, after which it
  182.      * will emit readyForUnload.
  183.      *
  184.      * Note that this is an asynchronous operation that may take some time
  185.      * with active chats. It's no longer immediate as it used to be in
  186.      * Kopete 0.7.x and before. This also means that you can do a clean
  187.      * shutdown.
  188.       * @note    The method is not private to allow subclasses to reimplement
  189.      *          it even more, but if you need to do this please explain why
  190.      *          on the list first. It might make more sense to add another
  191.      *          virtual for protocols that's called instead, but for now I
  192.      *          actually think protocols don't need their own implementation
  193.      *          at all, so I left out the necessary hooks on purpose.
  194.      *          - Martijn
  195.      */
  196.     virtual void aboutToUnload();
  197.  
  198. private slots:
  199.     /**
  200.      * @internal
  201.      * The account changed online status. Used while unloading the protocol.
  202.      */
  203.     void slotAccountOnlineStatusChanged( Kopete::Contact *self );
  204.  
  205.     /**
  206.      * @internal
  207.      * The account is destroyed. When it's the last account we emit the
  208.      * readyForUnload signal. Used while unloading the protocol.
  209.      */
  210.     void slotAccountDestroyed(  );
  211.  
  212.  
  213. public:
  214.  
  215.     /**
  216.      * @brief Deserialize the plugin data for a meta contact.
  217.      *
  218.      * This method splits up the data into the independent Kopete::Contact objects
  219.      * and calls @ref deserializeContact() for each contact.
  220.      *
  221.      * Note that you can still reimplement this method if you prefer, but you are
  222.      * strongly recommended to use this version of the method instead, unless you
  223.      * want to do _VERY_ special things with the data...
  224.      *
  225.      * @todo we probably should think to another way to save the contacltist.
  226.      */
  227.     virtual void deserialize( MetaContact *metaContact, const QMap<QString, QString> &serializedData );
  228.  
  229.     /**
  230.      * @brief Deserialize a single contact.
  231.      *
  232.      * This method is called by @ref deserialize() for each separate contact,
  233.      * so you don't need to add your own hooks for multiple contacts in a single
  234.      * meta contact yourself. @p serializedData and @p addressBookData will be
  235.      * the data the contact provided in Kopete::Contact::serialize.
  236.      *
  237.      * The default implementation does nothing.
  238.      *
  239.      * @return The contact created from the data
  240.      * @sa Contact::serialize
  241.      *
  242.      * @todo we probably should think to another way to save the contacltist.
  243.      */
  244.     virtual Contact *deserializeContact( MetaContact *metaContact,
  245.         const QMap<QString, QString> &serializedData,
  246.         const QMap<QString, QString> &addressBookData );
  247.  
  248.  
  249.  
  250. public slots:
  251.     /**
  252.      * A meta contact is about to save.
  253.      * Call serialize() for all contained contacts for this protocol.
  254.      * @internal
  255.      *   it's public because for example, Contact::setMetaContact uses it.
  256.      * @todo we probably should think to another way to save the contacltist.
  257.      */
  258.     void slotMetaContactAboutToSave( Kopete::MetaContact *metaContact );
  259.  
  260.  
  261. private:
  262.     class Private;
  263.     Private *d;
  264. };
  265.  
  266. } //END namespace kopete
  267.  
  268. #endif
  269.  
  270.